Add OpenCode integration — real-time conversation persistence plugin - #1524

Thanks everyone for the reviews. All suggestions have been addressed:

• python3 -m pip → safer pip invocation
• Fixed syntax highlighting on JSON block
• "plugin" → "plugins" (correct OpenCode config key)
• Removed unsupported keywords param from mempalace_kg_query instructions
• Install order: uv first, pip second, per @williamblair333's suggestion
  The plugin is published on npm as opencode-mempalace-persistence@1.0.1 and is running in production. Anything else needed before merge? Happy to make further changes.

Also worth noting: @igorls (https://github.com/igorls) reviewed the upstream OpenCode source adapter in #1484, which takes the pull approach for retrospective ingest. My plugin is the push side (real-time capture). They're complementary — install plugin + run mempalace mine --source opencode once for full coverage.
Additionally, empirical data from the MemPalace community shows that model choice significantly affects read-side invocation rates (tested on Cat-9a diagnostics: qwen3.5:4b invokes mempalace_search 87% vs gemma4:e4b at 40%). I'm planning to add a "recommended orchestrator" section to the README and a forced-invocation config flag as a belt-and-suspenders approach.
Happy to sync the documentation with the #1484 adapter once both land.

Thanks for this — the hook-based approach (chat.message + session.idle) is the right call over cron. Real-time delta sync with async mining is a clean design.
▎
▎ A few things from running MemPalace in production:
▎
▎ 1. Minimum version requirement
▎ PR #1523 (merged in v3.3.5) fixed critical HNSW corruption in repair --yes that causes link_lists.bin to grow to 100+ GB and OOM the host. Users on <3.3.5 would hit this silently during heavy use. Suggest adding mempalace>=3.3.5 to both install paths:

▎ uv tool install "mempalace>=3.3.5"
▎ python3 -m pip install "mempalace>=3.3.5"
▎
▎ 2. Concurrent mine call protection
▎ If chat.message fires in rapid succession, do mine calls serialize or can they overlap? Concurrent mines against the same palace can corrupt the SQLite FTS5 index. Worth documenting whether the plugin queues calls or relies on MemPalace's own locking.
▎
▎ 3. Wing categorization
▎ Auto-assigning to developer/creative/emotions/family/consciousness is opinionated — users with existing palaces may have different wing structures. Could this be made configurable, or at least noted as an override?
▎
▎ Otherwise LGTM — the async architecture and graceful shutdown fallback are solid.

@williamblair333 thanks for the thorough review. I've addressed all three points in v1.1.0:

1. Version pin — Updated all install instructions to mempalace>=3.3.5. The HNSW corruption fix is critical.

2. Concurrent mine protection — Refactored from per-wing parallel exec() calls to a single serialized mine call with a miningLock flag. No more concurrent FTS5 collisions possible.

3. Wing categorization — Removed the hardcoded 5-wing keyword system (categorize(), WING_KEYWORDS, wing subdirectories) entirely. Sessions are now exported flat to /tmp/oc-sessions/ and mined with a single mempalace mine --mode convos call — no --wing, no --extract. The model handles KG management via MCP tools (mempalace_kg_add/kg_query/kg_invalidate), same pattern as the Claude Code integration.

The KG regex extraction was also removed — MemPalace's own mining and the model's MCP tools handle that more reliably.

Plugin is at v1.1.0 on npm and the updated SKILL.md reflects all changes. Let me know if anything else is needed before merge.

Maintainer review (docs-only). This is mainly a trust/policy call for the org rather than a code issue:

The SKILL.md frontmatter install block auto-installs the npm package opencode-mempalace-persistence from github.com/geco (a personal account, not the MemPalace org), and every behavioral guarantee in the doc — turn capture, categorization, KG extraction, verbatim storage — lives in that external, unaudited package. Given MemPalace's privacy/verbatim posture, an official-repo doc that silently installs an unaffiliated package needs maintainer sign-off. At minimum, please add a clear "community / third-party, not maintained by the MemPalace team" disclaimer; ideally the org vets or forks the plugin.

Minor doc fixes: the ```json block in Step 3 starts with a # shell comment (invalid JSON if copy-pasted); and version: 1.1.0 vs the sibling openclaw doc's 3.3.0 is confusing for a doc living in this repo.

One correction to an earlier concern of mine: the "developer / creative / emotions / family / consciousness" buckets are not a design-principle violation — those map to the hall content-type classifier (config.py DEFAULT_TOPIC_WINGS / DEFAULT_HALL_KEYWORDS), which coexists with entity-first wings. It's just loose terminology in the doc (it says "wing" where the code means "hall", and "developer" should be "technical").

@igorls thanks for the thorough maintainer review. All points addressed in the latest commit:

1. Community disclaimer - Added a clear banner at the top of the SKILL.md, and the install label now says "(community)". The plugin README also carries the disclaimer.
2. JSON block - Fixed the shell comment inside the JSON code block. It's now valid, copy-paste safe.
3. Version - Changed from 1.1.0 to 3.3.5 to match the openclaw doc convention.
4. Wing vs Hall terminology - Since the plugin v1.1.1 no longer does any hardcoded categorization (sessions are exported flat), I've removed the old 5-category list entirely. The wing/hall confusion no longer applies.
5. Trust concern - The plugin is fully open at github.com/geco/opencode-mempalace-persistence (~120 lines TypeScript, v1.1.1 on npm). Happy to submit it for org audit, and I'm open to transferring the repo to the MemPalace organization if preferred.
   All updated in the latest commit on this branch. Let me know if anything else is needed.

@igorls @williamblair333 — bumping this for visibility. The plugin has evolved significantly since May. Here's what changed:
v1.2.0–v1.3.1

1. Added experimental.chat.messages.transform hook — the plugin now forcibly injects identity + relevant MemPalace memories into every prompt. No model discipline required.
2. autoInjectContext config flag — lives in ~/.mempalace/plugin-config.json (NOT in opencode.json, since OpenCode's schema validator rejects unknown keys).
3. AGENTS.md simplified to 2 KG-only steps (Query + Record). Memory search is handled by the plugin, not the model.
4. The SKILL.md in this PR should be updated to reflect all of this. Happy to push the changes once I get the green light.
   Next: v1.4.0 will make autoInjectContext: true the default.
   Would love a review when you have time.

Working through the same problem on the Claude Code side — hook-layer injection via UserPromptSubmit rather than model discipline — so this direction is directly relevant to us.

Two things on v1.2.0–v1.3.1:

1. experimental.chat.messages.transform — worth noting stability expectations or an OpenCode version range in the SKILL.md; if the hook changes without notice the doc goes stale.

2. autoInjectContext: true default in v1.4.0 — I'd suggest keeping it opt-in a bit longer. Your Cat-9a numbers (40% invocation on weaker models) indicate injected context isn't always useful, and the token cost adds up on lower-context models.

Happy to review the updated SKILL.md when pushed — just make sure @igorls's community disclaimer stays in.

@williamblair333 great points, thank you.
On both:

1. OpenCode version range — I've added a note to the SKILL.md (commit ffa8ce6) specifying that experimental.chat.messages.transform requires OpenCode 1.14+ and noting its stability. If the hook changes in the future, the doc will be updated.
2. autoInjectContext default — fair point on token cost. I'll keep it opt-in and drop the "v1.4.0 default" plan. The recommendation stays but the switch remains manual.
   The SKILL.md now has two new commits (20bb6e8 + ffa8ce6) reflecting the v1.3.1 state — auto-inject as recommended, simplified AGENTS.md, community disclaimer intact per @igorls's request. Would appreciate a final review when you have time.

Thanks for the update — working through the two new commits. Everything from my May and June reviews is addressed. A few new things from reading the full SKILL.md:

Bug: anyBins prerequisite check

requires:
  anyBins:
    - mempalace
    - python3

anyBins satisfies if any one binary is present. Python 3 is present everywhere, so this guard never actually checks for mempalace. A fresh user with no MemPalace installed sails through and fails silently at Step 1. Should be allBins (or just list mempalace alone — that's the real gate).

Design note: double MCP round-trip on every response
With autoInjectContext: true the plugin already runs mempalace search before every message. The AGENTS.md then adds a mandatory mempalace_mempalace_kg_query on top. So every single response — including quick code questions — incurs two MCP calls. Worth one sentence noting the latency/token cost on slow hardware or large palaces, so users can make an informed choice.

Design note: KG over-recording guidance
"err on the side of saving it" + "a session with zero KG entries is likely missing important information" is aggressive. Models will record noise, KG quality degrades, and the filter step gets noisier over time. "Record facts you're confident about" is less risky.

No concerns on the MemPalace integration design itself — version pin, serialized mining, flat export, opt-in inject are all correct. The npm package trust call remains @igorls's.

@williamblair333 all three points addressed in commit a5fc259:

1. anyBins → allBins — changed to allBins with just mempalace. The guard now correctly requires MemPalace to be installed before the skill is available.
2. Double MCP round-trip — added a performance note just before the AGENTS.md section explaining the two calls and typical latency.
3. KG over-recording — softened to "record facts you are confident about. Prefer quality over quantity." Also synced this language to the plugin's README and shipped as opencode-mempalace-persistence@1.3.2.

Plugin is at v1.3.2 on npm with a fully updated README and the same KG quality guidance.

@geco — all three look good.

allBins with just mempalace is the right call — clean gate, no Python false-pass. The performance note on the double round-trip is a transparency win (users can see what's happening and decide whether to pre-warm). "Quality over quantity" is the right framing for KG recording — it aligns with how I think about MemPalace entries generally.

v1.3.2 looks solid. From my side this is ready. Thanks for iterating on it this quickly.

I have been using your fork for a week. It worked out great. Thanks for sharing it. Had to make changes for windows version but I think mempalace isn't windows focused at all.

Thanks for iterating on this. I re-reviewed it during the agent-support merge pass.

This doc/plugin direction is still valuable, especially as the real-time "push" side for OpenCode. I merged the complementary #1484 OpenCode source adapter into codex/agent-support-community-merge, so the next revision here should probably be framed as the plugin/real-time layer that complements the first-party source adapter.

Before merge, I would like this updated for the current tree:

• Reference feat(sources): OpenCode adapter on RFC 002 contract #1484 / mempalace.sources.opencode as the built-in historical ingest path.
• Keep the community/third-party plugin disclaimer prominent in both frontmatter and body.
• Keep auto-injection opt-in, with the performance note for the extra search/KG calls.
• Verify the tool names against the current MCP tool surface; avoid instructions that invent unsupported params.
• Add a small Windows note if there are known plugin changes needed there, since a user reported local Windows adjustments.

Once the doc is synchronized with the landed source adapter and current plugin behavior, this looks like a good candidate for docs/integrations merge.

Status update — requesting re-review toward merge. The plugin just went through its biggest evolution (now opencode-mempalace-persistence@2.1.0 on npm), and this PR branch is updated accordingly.

Just pushed here: the section @igorls asked for — the SKILL.md now references mempalace.sources.opencode (#1484) and frames this plugin explicitly as the complementary real-time layer (source adapter = backfill history, plugin = never lose the present).

What changed since the June review round:

• AI checkpoints every 15 messages + pre-compaction emergency save (hooks decide when, model files via MCP)
• Synchronous exit save, per-project wings, mine --extract general, backfill mode
• Robustness from real-world reports: interpreter probing (pipx/uv/PATH), no-timeout mines (no orphaned lock-holders), all spawns shell-free (execFile argv)
• Bundled mempalace-recall skill (question-driven recall protocol, adapted from the official one)
• Housekeeping: community issues/PRs triaged and closed on the plugin repo (Shell injection via user message text in mempalaceSearch geco/opencode-mempalace-persistence#1, fix: prevent shell injection by using execFileSync/execFile instead of execSync/exec geco/opencode-mempalace-persistence#2, VENV_PYTHON path hardcoded for pipx — breaks when installed via uv geco/opencode-mempalace-persistence#3, fix: remove 2-min exec timeout that orphans mine processes geco/opencode-mempalace-persistence#4, fix: dead pipx python path; use native wake-up for context injection geco/opencode-mempalace-persistence#5)

Reviewer checklist status: allBins gate ✓, double round-trip transparency note ✓, KG quality-over-quantity ✓, community disclaimer ✓, #1484 framing ✓ (just pushed).

@williamblair333 @igorls — mind taking another look? Happy to address anything remaining.

Thanks for the thorough review, @igorls — this is exactly the kind of pass this needed. Addressed point by point (doc updated on this branch, plugin fixes landed on main as v2.2.0):

1. plugin key — fixed, my mistake. Also pinned the version (opencode-mempalace-persistence@2.2.0).
2. feat(sources): OpenCode adapter on RFC 002 contract #1484 wording — fixed to "once feat(sources): OpenCode adapter on RFC 002 contract #1484 merges". My bad for writing "ships".
3. Doc describes 2.2.0 now — wings, exchange mining, checkpoints, saveInterval, backfill env, startup mine. Stale v1.x claims removed.
4. Verbatim / exchange — you were right. The miner now uses default exchange extraction (one drawer per pair, verbatim); checkpoints + KG remain the intelligence layer on top. (Trade-off noted: no more auto-typed rooms; accepted for the verbatim guarantee.)
5. Capture gap — real bug, good catch. The message row exists before parts finish streaming, so mid-reply exports truncated replies while the cursor moved on. Fixed two ways: the export skips unfinished assistant messages (finish tracking) and clamps the cursor behind them, and mines now run on idle/exit/startup only — never mid-reply snapshots.
6. Exit path — bounded: 45s total budget, 30s per wing, leftovers covered by the new startup mine. miningLock is deliberately ignored at exit (any async mine dies with the process; the sync mine takes ownership — documented in code).
7. Privacy — moved: exports and helper script now live under ~/.mempalace/oc-sessions/ (0700, files 0600). No more world-readable /tmp artifacts.
8. Windows — binary now resolves from PATH (MEMPALACE_BIN override), win32 dropped from frontmatter, Windows note added (untested, reports welcome).
9. Hygiene — version pinned, single mempalace_mempalace_* convention, CRITICAL block replaced with a link to integrations/shared/recall-protocol.md + conditional search, AGENTS.md says append-don't-overwrite, <500ms replaced with an honest cold-start note (~20s first search), version: set to 2.2.0.

On the open question (skill vs guide page): happy either way — a website/guide/opencode.md page linking the plugin as third-party works for me if you prefer it there.

Re-review welcome whenever suits.

Small update, no action needed — just keeping the thread accurate while you have bigger fish to fry.

The plugin is now at 2.5.1 on npm (all dogfooded daily). Since my last note: TUI toasts for mines, checkpoints and MCP calls (opt-out), a read-only /memory-log over a structured interaction log, SIGHUP-safe exit saves, backoff retries so two concurrent instances interleave instead of starving, and remaining-to-mine counts on completion.

The SKILL.md on this branch describes the 2.2.0 behavior; I'll sync it to latest whenever you signal the direction is still good — didn't want to churn the branch on every release.

@igorls @williamblair333 — whenever you have a moment, no rush at all.

Brief update, no rush at all — just keeping the thread honest.

The plugin is now at 2.8.1 on npm. Notable since my last note: message-level export dedup (each message is archived exactly once — this, not context size, was the real fix for near-duplicate recall), per-wing sync cursors (one slow project can no longer stall the others), and a community-reported ENOBUFS fix that made exports resilient for users with very large sessions.

Adoption is growing on its own: ~2,000 npm downloads/week and daily dogfooding on my trading-bot setup, so this feels like a useful integration to have available for OpenCode users.

I know review capacity is finite — whenever you get a chance to re-check the branch (it's synced to the latest behavior), I'm happy to address anything that remains. Thanks!

P.S. The "Changes requested" label on a PR clears automatically as soon as a reviewer re-reviews and approves — there's no way (and no need) for me to remove it myself; it just needs the next review pass.

Update from the plugin side, no action needed — just keeping the thread current.

OpenCode 2 landed and the plugin now supports it. v2 changed both the plugin contract and the on-disk session layout, so two things were needed:

• Dual entrypoint. v2 requires export default { id, setup() }; the v1 factory export fails to load outright ("Plugin must export a default definition with an id and an effect or setup function"). The package now ships both — the existing v1 hook map untouched, plus a 1:1 port on Plugin.define — so one install works before and after a user moves to v2.
• Dual-schema transcript export. v2 stores sessions in session_v2 / session_message (human turn in a plain text field, replies in content[] blocks) while v1 used session / message / part. The export reads both and unions them by session id, v2 first, so a v1 → v2 migration never strands messages. A user-reported failure on 2.0.19 is what surfaced this: the hooks fired, but the export died on the old table names and nothing was being saved.

The bug worth reporting to other integrations. The sync cursor used to advance only after a successful mine. The export is cheap and idempotent; the mine is expensive and fails for reasons outside the plugin's control (palace lock held elsewhere, killed at exit, OOM). So a mine that never finished pinned the cursor forever, every later export re-cut its window from the same stale point, and because the session kept growing each file was a superset of the previous one. One long-running session produced 691 overlapping files; mining them all multiplied every message by up to 691 — 628k drawers, 5 GB, with no error anywhere. The cursor now advances on write, so windows are disjoint by construction and the pending file is simply the queue. Full write-up in the README: https://github.com/geco/opencode-mempalace-persistence#the-cursor-means-exported-not-mined

One caveat, stated plainly: v2's server runtime has no toast surface, so the plugin's TUI notifications are silent there today. v2 does expose a TUI-side entry point with ui.toast, slot rendering and OS notifications — we're adding a ./tui export for it, and /memory-status plus /memory-log work on both regardless.

Adoption is steady at ~2,700 npm downloads in the last 30 days, on top of the daily dogfooding on my trading-bot setup.

Still happy to rebase the skill file onto whatever the current MemPalace behaviour is whenever you have a moment to look at it.